home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / src / xdoc / notangle.1 < prev    next >
Encoding:
Text File  |  1995-05-30  |  13.7 KB  |  538 lines  |  [TEXT/MPS ]
  1. .TH NOWEB 1 "local 4/19/93"
  2. .SH NAME
  3. notangle, noweave, nountangle \- noweb, a literate-programming tool
  4. .SH SYNOPSIS
  5. .B notangle
  6. [\fB-R\fProotname] [\fB-filter\fP command]
  7. [\fB-L\fP[format]] [file] ...
  8. .br
  9. \fBnountangle\fP 
  10. [\fB-ml\fP|\fB-m3\fP|\fB-c\fP|\fB-c++\fP|\fB-awk\fP|\fB-tex\fP|\fB-f77\fP|\fB-f90\fP]
  11. [\fB-R\fProotname] [\fB-filter\fP command] [\fB-w\fPwidth] [file] ...
  12. .br
  13. \fBnoweave\fP [options] [file] ...
  14. .SH DESCRIPTION
  15. .I Noweb
  16. is a literate-programming tool like Knuth's
  17. .I WEB,
  18. only simpler.
  19. A 
  20. .I noweb
  21. file contains program source code interleaved with documentation.
  22. When 
  23. .I notangle
  24. is given a 
  25. .I noweb
  26. file, it writes the program on standard output.
  27. When 
  28. .I noweave
  29. is given a 
  30. .I noweb
  31. file, it reads the 
  32. .I noweb
  33. source and produces, on standard output, \fILaTeX\fP, \fITeX\fP, or \fIHTML\fP
  34. source for typeset documentation.
  35. .I nountangle
  36. converts a literate program into an ordinary program by
  37. turning interleaved documentation into comments.
  38. The file name `-' refers to standard input.
  39. .SH FORMAT OF NOWEB FILES
  40. A 
  41. .I noweb 
  42. file is a sequence of
  43. .I chunks,
  44. which may appear in any order.
  45. A chunk may contain code or documentation.
  46. Documentation chunks begin with a line that starts with an at sign (@) 
  47. followed by a space or newline.
  48. They have no names.
  49. Code chunks begin with
  50. .br
  51. <<\fIchunk name\fP>>=
  52. .br
  53. on a line by itself.
  54. The double left angle bracket (<<) must be in the first column.
  55. Chunks are terminated by the beginning of another chunk, or by end of file.
  56. If the first line in the file does not mark the beginning of a
  57. chunk, it is assumed to be the first line of a documentation chunk.
  58. .PP
  59. Documentation chunks contain text that is ignored by
  60. .I notangle
  61. and copied verbatim to 
  62. standard output
  63. by
  64. .I noweave
  65. (except for quoted code).
  66. .I noweave
  67. can work with \fILaTeX\fP, plain \fITeX\fP, or \fIHTML\fP.
  68. With plain \fITeX\fP, it inserts a reference to a 
  69. .I TeX
  70. macro package, \fInwmac\fP, which defines commands like
  71. .B \echapter
  72. and
  73. .B \esection.
  74. .PP
  75. Code chunks contain program source code and references to other code
  76. chunks.
  77. Several code chunks may have the same name;
  78. .I notangle
  79. concatenates their definitions to produce a single chunk, just as does
  80. .I tangle(1).
  81. Code chunk definitions are like macro definitions;
  82. .I notangle
  83. extracts a program by expanding one chunk (by default, the chunk named
  84. \fB<<\fP*\fB>>\fP).
  85. The definition of that chunk contains references to other chunks, which are 
  86. themselves expanded, and so on.
  87. \fInotangle\fP's output is readable; it preserves the indentation of expanded
  88. chunks with respect to the chunks in which they appear.
  89. .PP
  90. Code may be quoted within documentation
  91. chunks by placing double square brackets
  92. (\fB[[\fI...\fB]]\fR) around it.
  93. These double square brackets are ignored by
  94. .I notangle,
  95. but they may be used by 
  96. .I noweave
  97. to give the code special typographic treatment, e.g., hypertext links.
  98. If quoted code ends with three or more square brackets,
  99. .I noweave
  100. choose the rightmost pair, so that, for example, \fB[[a[i]]]\fR is
  101. parsed correctly.
  102. .PP
  103. If double left and right angle brackets are not paired, they are
  104. treated as literal \fB<<\fP and \fB>>\fP.  Users can force any
  105. such brackets, even paired brackets, to be treated as literal by
  106. using a preceding at sign (e.g. \fB@<<\fP).
  107. .PP
  108. Any line beginning with `\fB@ \fP' terminates a code chunk,
  109. but if the line has the form
  110. .br
  111. \fB@ %def \fP\fIidentifiers\fP
  112. .br
  113. it is taken to mean that the preceding chunk defines the identifiers listed 
  114. in 
  115. .I identifiers.
  116. This list contains identifiers separated by whitespace; 
  117. any sequence of nonwhite characters may be an identifier.
  118. .I noweb
  119. uses a simple heuristic to avoid recognizing identifiers 
  120. that are substrings of other identifiers.
  121. .SH TANGLING
  122. .I notangle
  123. and
  124. .I nountangle
  125. accept the same set of options, although some options have effects only on one 
  126. or the other.
  127. The options are:
  128. .TP
  129. .B -R\fIname\fR
  130. Expand the \fB<<\fIname\fB>>\fR code chunk instead of \fB<<\fP*\fB>>\fP.
  131. .TP
  132. .B -L\fIformat\fR
  133. Emit line number indications at chunk boundaries.
  134. A line number indication identifies the source of the line that follows it.
  135. In
  136. .I format,
  137. .B "%F"
  138. indicates the name of the source file,
  139. .B "%L"
  140. indicates the line number of the source file,
  141. .B "%N"
  142. indicates a newline,
  143. and 
  144. .B "%%"
  145. indicates a percent sign.
  146. A sign and digit may be inserted between the percent sign and the `\fBL\fP',
  147. in which case the line number will be adjusted by that amount.
  148. If 
  149. .I format
  150. is omitted, the default format is that accepted by the C preprocessor:
  151. `\fB#line %L "%F"%N\fR'.
  152. When using the \fB-L\fIformat\fR option, 
  153. .I notangle
  154. ensures that all text appears in the same column in input and output.
  155. .I nountangle
  156. ignores this option.
  157. .TP
  158. .B \-t\fIk\fP
  159. Copy tabs untouched from input to output, and use tabs for indentation, 
  160. assuming stops every \fIk\fP columns.
  161. By default, tabs are expanded to spaces with stops every 8 columns.
  162. .TP
  163. .B \-filter \fIcmd\fP
  164. Filter the 
  165. .I noweb
  166. source through 
  167. .I cmd
  168. after converting it to tool form and before tangling.
  169. .I notangle
  170. looks for 
  171. .I cmd
  172. first on the user's
  173. .B PATH,
  174. then in
  175. .B |LIBDIR|.
  176. Such filters
  177. can be used to add features to
  178. .I notangle;
  179. for an example see
  180. .B |LIBDIR|/emptydefn.
  181. For experts only.
  182. .TP
  183. .B "\-markup \fIparser\fP"
  184. Use 
  185. .I parser
  186. to parse the input file.
  187. Enables use of noweb tools on files in other formats;
  188. for example, the 
  189. .B numarkup
  190. parser understands
  191. .I nuweb(1)
  192. format.
  193. See 
  194. .I nowebfilters(1)
  195. for more information.
  196. For experts only.
  197. .TP
  198. .B "-awk | -c | -icn | -icon | -ml | -m3 | -pascal | -f77 | -f90 | -tex"
  199. When 
  200. .I nountangle
  201. transforms documentation chunks into comments, use the comment format of the language
  202. named.
  203. .B \-c
  204. is the default.
  205. .I notangle
  206. ignores these options.
  207. .TP
  208. .B -w\fIn\fP
  209. When 
  210. .I nountangle
  211. transforms documentation chunks into comments, create comments on lines of width \fIn\fP.
  212. .I notangle
  213. ignores this option.
  214. .SH WEAVING
  215. Output from \fInoweave\fP can
  216. be used in \fITeX\fP documents that 
  217. .B "\\\\input nwmac,"
  218. in \fILaTeX\fP documents that  use the
  219. .B noweb
  220. document-style option (see \fInowebstyle(1)\fP),
  221. and in \fIHTML\fP documents to be browsed with 
  222. .I Mosaic(1).
  223. .I Noweave
  224. treats code chunks somewhat like
  225. .I LaTeX list environments.
  226. If the ``\fB@ \fP'' that terminates a code chunk is followed immediately by text,
  227. that text follows the code chunk without a paragraph break.
  228. If the rest of the line is blank, 
  229. .I noweave
  230. puts 
  231. .I TeX
  232. into ``vertical mode,'' and later text starts a fresh, indented paragraph.
  233. .PP
  234. No page breaks occur in the middle of code chunks unless necessary to avoid
  235. an overfull vbox.
  236. The documentation chunk immediately preceding a code chunk appears on
  237. the same page as that code chunk unless doing so would violate the previous rule.
  238. .PP
  239. .I Noweave
  240. inserts no extra newlines in its \fITeX\fP output, so the line numbers given
  241. in
  242. .I TeX
  243. error messages are the same as those in the input file.
  244. .PP
  245. .I noweave
  246. has
  247. options that dictate choice of 
  248. formatter
  249. and that support different formatting idioms and tools.
  250. Basic options are described here; options related to index
  251. and cross-reference information are described in the 
  252. INDEXING AND CROSS-REFERENCE section.
  253. .TP
  254. .B \-latex
  255. Use LaTeX wrapper in 
  256. .B article
  257. style with
  258. .B noweb
  259. style option and page style. (Default)
  260. .TP 
  261. .B \-tex
  262. Use plain TeX wrapper and the
  263. .B nwmac
  264. macros.
  265. .TP
  266. .B \-html
  267. Format the program for HTML, not TeX or LaTeX. 
  268. If \fB-n\fP is not given, use HTML wrapper as well.
  269. The output is uninteresting without \fB-index\fP or \fB-x\fP.
  270. The tags \fB<nowebchunks>\fP and \fB<nowebindex>\fP, on lines by themselves,
  271. produce a list of chunks and an index of identifiers, respectively.
  272. If these tags are not present, the list and index are placed at the end of the file.
  273. .TP
  274. .B \-latex+html
  275. Assume documentation chunks are LaTeX, but generate HTML for code chunks,
  276. suitably marked so conversion with 
  277. .I latex2html(1)
  278. yields reasonable output.
  279. A LaTeX wrapper is implied, but can be turned off with \fB-n\fP.
  280. .TP
  281. .B \-n
  282. Don't use any wrapper (header or trailer).
  283. This option is useful when \fInoweave\fP's output will be
  284. a part of a larger document.
  285. See also 
  286. .B \-delay.
  287. .TP
  288. .B \-filter \fIcmd\fP
  289. Filters the 
  290. .I noweb
  291. source through 
  292. .I cmd
  293. after converting it to tool form and before converting to
  294. .I TeX.
  295. .I noweave
  296. looks for 
  297. .I cmd
  298. first on the user's
  299. .B PATH,
  300. then in
  301. .B |LIBDIR|.
  302. Such filters
  303. can be used to add features to
  304. .I noweave;
  305. for an example, see
  306. .B |LIBDIR|/noxref.krom.
  307. .I Noweave
  308. supports up to four filters; one can get more by shell trickery, 
  309. for example, \fB-filter "icon.filter | noidx"\fP.
  310. The \fB-autodefs\fP,
  311. \fB-x\fP, \fB-index\fP, and \fB-indexfrom\fP options are implemented as filters.
  312. .TP
  313. .B "\-markup \fIparser\fP"
  314. Use 
  315. .I parser
  316. to parse the input file.
  317. Enables use of noweb tools on files in other formats;
  318. for example, the 
  319. .B numarkup
  320. parser understands
  321. .I nuweb(1)
  322. format.
  323. See 
  324. .I nowebfilters(1)
  325. for more information.
  326. For experts only.
  327. .TP 
  328. .B \-option \fIopt\fP
  329. Adds \fB\enoweboptions{\fP\fIopt\fP\fB}\fP to the
  330. .I LaTeX
  331. header.
  332. Works only with the
  333. .B \-latex
  334. option.
  335. See 
  336. .I nowebstyle(1) 
  337. for values of
  338. .I opt.
  339. .TP
  340. .B \-delay
  341. By default, 
  342. .I noweave
  343. puts file-name and other information into the output before the first chunk
  344. of the program.
  345. .B \-delay
  346. delays that information until after the first documentation chunk, making
  347. act a little bit like the 
  348. .I WEB
  349. ``limbo.''
  350. The option is typically used to enable a user to put a specialized
  351. .I LaTeX
  352. .B "\\\\documentstyle"
  353. command and other preamble material in the first documentation chunk.
  354. This option also forces trailing cross-referencing information to be emitted
  355. just before the final chunk, instead of at the end of the document;
  356. the final chunk is expected to contain
  357. .B "\\\\end{document}."
  358. The 
  359. .B \-delay
  360. option implies the
  361. .B \-n 
  362. option.
  363. .TP
  364. .B \-t\fIk\fP
  365. Expand tabs with stops every \fIk\fP columns.
  366. (Default is to expand every 8 columns.)
  367. .TP
  368. .B \-t
  369. Copy tabs to the output.
  370. .TP
  371. .B \-v
  372. Print the pipeline on standard error.
  373. .SH INDEXING AND CROSS-REFERENCE
  374.  
  375. When used with 
  376. .I LaTeX 
  377. or
  378. .I HTML,
  379. .I noweave
  380. can provide indexing and cross-reference information for chunks and for 
  381. programming-language identifiers.
  382. Identifier definitions may be marked by hand using \fB@ %def\fP, 
  383. or for some languages they may be found automatically using the 
  384. \fB-autodefs\fP option.
  385. This section describes the indexing and cross-reference options;
  386. it might well be skipped on first reading.
  387. .TP
  388. .B \-x
  389. For 
  390. .I LaTeX,
  391. add a page number to each chunk name identifying the location of that
  392. chunk's definition, and emit cross-reference information relating definitions and uses.
  393. For 
  394. .I HTML,
  395. create hypertext links between uses and definitions of chunks.
  396. When
  397. .B noweave -x
  398. is used with
  399. .I LaTeX,
  400. the control sequence
  401. .B "\\\\nowebchunks"
  402. expands to a sorted list of all code chunks.
  403. .TP
  404. .B \-index
  405. Build cross-reference information (or hypertext links) for identifiers defined by
  406. .br
  407. .B "@ %def" 
  408. .I identifiers
  409. .br
  410. Definitions are those found in input files.
  411. Requires
  412. .I LaTeX
  413. or
  414. .I HTML.
  415. .B \-index
  416. implies
  417. .B \-x;
  418. including both will generate strange-looking output.
  419. .I noweave
  420. does not generate
  421. cross-references to identifiers that appear in quoted code (\fB@[[\fP...\fB@]]\fP),
  422. but it does generate hypertext links.
  423. When
  424. .B noweave -index
  425. is used with
  426. .I LaTeX, 
  427. the control sequence
  428. .B "\\\\nowebindex"
  429. expands to an index of identifiers.
  430. .TP
  431. .B \-indexfrom \fIindex\fP
  432. Like 
  433. .B \-index,
  434. but the identifiers to be indexed are taken from file \fIindex\fP.
  435. See
  436. .I noindex(1).
  437. .TP
  438. .B \-autodefs \fIlang\fP
  439. Discover identifier definitions automatically.
  440. Code in chunks must be in language \fIlang\fP.
  441. Permissible \fIlang\fPs vary but may include
  442. .B tex
  443. or 
  444. .B icon.
  445. Useless without
  446. .B \-index,
  447. which it must precede.
  448. .TP
  449. .B \-showautodefs
  450. Show values of \fIlang\fP usable with \fB-autodefs\fP.
  451. .SH ERROR MESSAGES
  452. If
  453. .I notangle
  454. or
  455. .I noweave
  456. encounters a chunk name within documentation, it assumes that this
  457. indicates an error, usually misspelling ``<<name>>=''.
  458. Other error messages should be self-explanatory.
  459. .PP
  460. It is incorrect to refer to a chunk that is never
  461. defined, but it is OK for chunks to be defined and not used.
  462. .SH FILES
  463. .PP
  464. .ta \w'|TEXINPUTS|nwkernel.texxxxx'u
  465. .nf
  466. |LIBDIR|/markup    markup preprocessor
  467. |LIBDIR|/unmarkup    inverts markup
  468. |LIBDIR|/nt    notangle proper
  469. |LIBDIR|/finduses    find uses of identifiers for index
  470. |LIBDIR|/noidx    generate index and cross-reference info
  471. |LIBDIR|/totex    back end to emit \fITeX\fP or \fILaTeX\fP
  472. |LIBDIR|/tohtml    back end to emit HTML
  473. |TEXINPUTS|/nwmac.tex    formatting \fITeX\fP macros
  474. |TEXINPUTS|/noweb.sty    use in \fILaTeX\fP documents; see \fInowebstyle(1)\fP
  475. .fi
  476. .SH SEE ALSO
  477. .PP
  478. .I cpif(1), nodefs(1), noroots(1), noweb(1), noindex(1), nowebstyle(1), nowebfilters(1)
  479. .SH BUGS
  480. .I notangle 
  481. and
  482. .I nountangle
  483. fail if names used on the command line contain single quotes.
  484. .PP
  485. Ignoring unused chunks can cause problems;
  486. if a chunk has
  487. multiple definitions and one is misspelled,
  488. the misspelled definition is silently ignored.
  489. .I noroots(1)
  490. can be used to catch this mistake.
  491. .PP
  492. .I noweb
  493. requires the new version of
  494. .I awk,
  495. assumed to be called
  496. .I nawk.
  497. DEC
  498. .I nawk
  499. has a bug in that that causes 
  500. .B noweave
  501. to fail to translate braces correctly.
  502. GNU 
  503. .I gawk
  504. is reported to work.
  505. .PP
  506. DEC 
  507. .I sh
  508. has a bug that causes the
  509. .B \-filter
  510. option to fail whenever the filter command contains more than one word.
  511. .PP
  512. The default
  513. .I LaTeX
  514. pagestyles don't set the width of the boxes containing headers and footers.
  515. Since 
  516. .I noweb
  517. code paragraphs are extra wide, this 
  518. .I LaTeX
  519. bug sometimes results in extra-wide headers and footers.
  520. The remedy is to redefine the relevant 
  521. .B ps@*
  522. commands;
  523. .B ps@noweb
  524. in 
  525. .B noweb.sty
  526. can be used as an example.
  527. .PP
  528. .I latex2html(1)
  529. mangles some source files.
  530. .PP
  531. .I noweave
  532. has too many options, and this man page is too long.
  533. .SH AUTHOR
  534. Norman Ramsey, Bellcore.
  535. Internet address \fBnorman@bellcore.com\fP.
  536. .br
  537. Noweb home page at \fBftp://bellcore.com/pub/norman/www/noweb/intro.html\fP.
  538.